home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / interp / perl5.005.tar.gz / perl5.005.tar / perl5.005 / pod / perlmodinstall.pod < prev    next >
Text File  |  1998-07-22  |  11KB  |  408 lines
  1. =head1 NAME
  2.  
  3. perlmodinstall - Installing CPAN Modules
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. You can think of a module as the fundamental unit of reusable Perl
  8. code; see L<perlmod> for details.  Whenever anyone creates a chunk of
  9. Perl code that they think will be useful to the world, they register
  10. as a Perl developer at http://www.perl.com/CPAN/modules/04pause.html
  11. so that they can then upload their code to the CPAN.  The CPAN is the
  12. Comprehensive Perl Archive Network and can be accessed at
  13. http://www.perl.com/CPAN/.
  14.  
  15. This documentation is for people who want to download CPAN modules
  16. and install them on their own computer.
  17.  
  18. =head2 PREAMBLE
  19.  
  20. You have a file ending in .tar.gz (or, less often, .zip).  You know
  21. there's a tasty module inside.  There are four steps you must now
  22. take:
  23.  
  24. =over 5
  25.  
  26. =item B<DECOMPRESS> the file
  27. =item B<UNPACK> the file into a directory
  28. =item B<BUILD> the module (sometimes unnecessary)
  29. =item B<INSTALL> the module.
  30.  
  31. =back
  32.  
  33. Here's how to perform each step for each operating system.  This is
  34. I<not> a substitute for reading the README and INSTALL files that
  35. might have come with your module!
  36.  
  37. Also note that these instructions are tailored for installing the
  38. module into your system's repository of Perl modules.  But you can
  39. install modules into any directory you wish.  For instance, where I
  40. say C<perl Makefile.PL>, you can substitute C<perl
  41. Makefile.PL PREFIX=/my/perl_directory> to install the modules
  42. into C</my/perl_directory>.  Then you can use the modules
  43. from your Perl programs with C<use lib
  44. "/my/perl_directory/lib/site_perl";> or sometimes just C<use
  45. "/my/perl_directory";>.  
  46.  
  47. =over 4
  48.  
  49. =item *
  50.  
  51. B<If you're on Unix,>
  52.  
  53. You can use Andreas Koenig's CPAN module 
  54. ( http://www.perl.com/CPAN/modules/by-module/CPAN ) 
  55. to automate the following steps, from DECOMPRESS through INSTALL.
  56.  
  57. A. DECOMPRESS 
  58.  
  59. Decompress the file with C<gzip -d yourmodule.tar.gz>
  60.  
  61. You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. 
  62.  
  63. Or, you can combine this step with the next to save disk space:
  64.  
  65.      gzip -dc yourmodule.tar.gz | tar -xof -
  66.  
  67. B. UNPACK
  68.  
  69. Unpack the result with C<tar -xof yourmodule.tar>
  70.  
  71. C. BUILD
  72.  
  73. Go into the newly-created directory and type:
  74.  
  75.       perl Makefile.PL
  76.       make
  77.       make test
  78.  
  79. D. INSTALL
  80.  
  81. While still in that directory, type:
  82.  
  83.       make install
  84.  
  85. Make sure you have the appropriate permissions to install the module
  86. in your Perl 5 library directory.  Often, you'll need to be root.
  87.  
  88. That's all you need to do on Unix systems with dynamic linking.
  89. Most Unix systems have dynamic linking -- if yours doesn't, or if for
  90. another reason you have a statically-linked perl, B<and> the
  91. module requires compilation, you'll need to build a new Perl binary
  92. that includes the module.  Again, you'll probably need to be root.
  93.  
  94. =item *
  95.  
  96. B<If you're running Windows 95 or NT with the ActiveState port of Perl>
  97.  
  98.    A. DECOMPRESS
  99.  
  100. You can use the shareware Winzip ( http://www.winzip.com ) to
  101. decompress and unpack modules.
  102.  
  103.    B. UNPACK
  104.  
  105. If you used WinZip, this was already done for you.
  106.  
  107.    C. BUILD
  108.  
  109. Does the module require compilation (i.e. does it have files
  110. that end in .xs, .c, .h, .y, .cc, .cxx, or .C)?  If it does, you're on
  111. your own.  You can try compiling it yourself if you have a C compiler.
  112. If you're successful, consider uploading the resulting binary to the
  113. CPAN for others to use.  If it doesn't, go to INSTALL.
  114.  
  115.    D. INSTALL
  116.  
  117. Copy the module into your Perl's I<lib> directory.  That'll be one
  118. of the directories you see when you type 
  119.  
  120.    perl -e 'print "@INC"'
  121.  
  122. =item *
  123.  
  124. B<If you're running Windows 95 or NT with the core Windows distribution of Perl,>
  125.  
  126.    A. DECOMPRESS
  127.  
  128. When you download the module, make sure it ends in either
  129. C<.tar.gz> or C<.zip>.  Windows browsers sometimes
  130. download C<.tar.gz> files as C<_tar.tar>, because
  131. early versions of Windows prohibited more than one dot in a filename.
  132.  
  133. You can use the shareware WinZip ( http://www.winzip.com ) to
  134. decompress and unpack modules.
  135.  
  136. Or, you can use InfoZip's C<unzip> utility (
  137. http://www.cdrom.com/pub/infozip/Info-Zip.html ) to uncompress
  138. C<.zip> files; type C<unzip yourmodule.zip> in
  139. your shell.
  140.  
  141. Or, if you have a working C<tar> and C<gzip>, you can
  142. type
  143.  
  144.    gzip -cd yourmodule.tar.gz | tar xvf -
  145.  
  146. in the shell to decompress C<yourmodule.tar.gz>.  This will
  147. UNPACK your module as well.
  148.  
  149.    B. UNPACK
  150.  
  151. All of the methods in DECOMPRESS will have done this for you.
  152.  
  153.    C. BUILD
  154.  
  155. Go into the newly-created directory and type:
  156.  
  157.       perl Makefile.PL
  158.       dmake
  159.       dmake test
  160.  
  161. Depending on your perl configuration, C<dmake> might not be
  162. available.  You might have to substitute whatever C<perl
  163. -V:make> says. (Usually, that will be C<nmake> or
  164. C<make>.)
  165.  
  166.    D. INSTALL
  167.  
  168. While still in that directory, type:
  169.  
  170.       dmake install
  171.  
  172. =item *
  173.  
  174. B<If you're using a Macintosh,>
  175.  
  176. A. DECOMPRESS
  177.  
  178. You can either use StuffIt Expander ( http://www.aladdinsys.com/ ) in
  179. combination with I<DropStuff with Expander Enhancer>
  180. (shareware), or the freeware MacGzip (
  181. http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
  182.  
  183. B. UNPACK
  184.  
  185. If you're using DropStuff or Stuffit, you can just extract the tar
  186. archive.  Otherwise, you can use the freeware I<suntar> (
  187. http://www.cirfid.unibo.it/~speranza ).
  188.  
  189. C. BUILD
  190.  
  191. Does the module require compilation? 
  192.  
  193. 1. If it does,
  194.  
  195. Overview: You need MPW and a combination of new and old CodeWarrior
  196. compilers for MPW and libraries.  Makefiles created for building under
  197. MPW use the Metrowerks compilers.  It's most likely possible to build
  198. without other compilers, but it has not been done successfully, to our
  199. knowledge.  Read the documentation in MacPerl: Power and Ease (
  200. http://www.ptf.com/macperl/ ) on porting/building extensions, or find
  201. an existing precompiled binary, or hire someone to build it for you.
  202.  
  203. Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch)
  204. to build it for you.  To subscribe to the mac-perl mailing list, send
  205. mail to mac-perl-request@iis.ee.ethz.ch.
  206.  
  207. 2. If the module doesn't require compilation, go to INSTALL.
  208.  
  209. D. INSTALL
  210.  
  211. Make sure the newlines for the modules are in Mac format, not Unix format.
  212. Move the files manually into the correct folders.
  213.  
  214. Move the files to their final destination: This will
  215. most likely be in C<$ENV{MACPERL}site_lib:> (i.e.,
  216. C<HD:MacPerl folder:site_lib:>).  You can add new paths to
  217. the default C<@INC> in the Preferences menu item in the
  218. MacPerl application (C<$ENV{MACPERL}site_lib:> is added
  219. automagically).  Create whatever directory structures are required
  220. (i.e., for C<Some::Module>, create
  221. C<$ENV{MACPERL}site_lib:Some:> and put
  222. C<Module.pm> in that directory).
  223.  
  224. Run the following script (or something like it):
  225.  
  226.      #!perl -w
  227.      use AutoSplit;
  228.      my $dir = "${MACPERL}site_perl";
  229.      autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1);
  230.  
  231. Eventually there should be a way to automate the installation process; some
  232. solutions exist, but none are ready for the general public yet.
  233.  
  234. =item *
  235.  
  236. B<If you're on the DJGPP port of DOS,>
  237.  
  238.    A. DECOMPRESS
  239.  
  240. djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ )
  241. will both uncompress and unpack.  
  242.  
  243.    B. UNPACK
  244.  
  245. See above.
  246.  
  247.    C. BUILD
  248.  
  249. Go into the newly-created directory and type:
  250.  
  251.       perl Makefile.PL
  252.       make
  253.       make test
  254.  
  255. You will need the packages mentioned in C<Readme.dos>
  256. in the Perl distribution.
  257.  
  258.    D. INSTALL
  259.  
  260. While still in that directory, type:
  261.  
  262.      make install    
  263.      
  264. You will need the packages mentioned in Readme.dos in the Perl distribution.
  265.  
  266. =item *
  267.  
  268. B<If you're on OS/2,>
  269.  
  270. Get the EMX development suite and gzip/tar, from either Hobbes (
  271. http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
  272. the instructions for Unix.
  273.  
  274. =item *
  275.  
  276. B<If you're on VMS,>
  277.  
  278. When downloading from CPAN, save your file with a C<.tgz>
  279. extension instead of C<.tar.gz>.  All other periods in the
  280. filename should be replaced with underscores.  For example,
  281. C<Your-Module-1.33.tar.gz> should be downloaded as
  282. C<Your-Module-1_33.tgz>.
  283.  
  284. A. DECOMPRESS
  285.  
  286. Type 
  287.  
  288.     gzip -d Your-Module.tgz
  289.  
  290. or, for zipped modules, type 
  291.  
  292.     unzip Your-Module.zip
  293.  
  294. Executables for gzip, zip, and VMStar ( Alphas:
  295. http://www.openvms.digital.com/cd/000TOOLS/ALPHA/ and Vaxen:
  296. http://www.openvms.digital.com/cd/000TOOLS/VAX/ ).  
  297.  
  298. gzip and tar
  299. are also available at ftp://ftp.digital.com/pub/VMS.
  300.  
  301. Note that GNU's gzip/gunzip is not the same as Info-ZIP's zip/unzip
  302. package.  The former is a simple compression tool; the latter permits
  303. creation of multi-file archives.
  304.  
  305. B. UNPACK
  306.  
  307. If you're using VMStar:
  308.  
  309.      VMStar xf Your-Module.tar
  310.  
  311. Or, if you're fond of VMS command syntax:
  312.  
  313.      tar/extract/verbose Your_Module.tar
  314.  
  315. C. BUILD 
  316.  
  317. Make sure you have MMS (from Digital) or the freeware MMK ( available from MadGoat at  http://www.madgoat.com ).  Then type this to create the
  318. DESCRIP.MMS for the module: 
  319.  
  320.     perl Makefile.PL
  321.  
  322. Now you're ready to build:
  323.  
  324.     mms
  325.     mms test
  326.  
  327. Substitute C<mmk> for C<mms> above if you're using MMK.
  328.  
  329. D. INSTALL
  330.  
  331. Type 
  332.  
  333.     mms install
  334.  
  335. Substitute C<mmk> for C<mms> above if you're using MMK.
  336.  
  337. =item *
  338.  
  339. B<If you're on MVS>,
  340.  
  341. Introduce the .tar.gz file into an HFS as binary; don't translate from
  342. ASCII to EBCDIC.
  343.  
  344. A. DECOMPRESS 
  345.  
  346.       Decompress the file with C<gzip -d yourmodule.tar.gz>
  347.  
  348.       You can get gzip from 
  349.       http://www.s390.ibm.com/products/oe/bpxqp1.html.
  350.  
  351. B. UNPACK
  352.  
  353. Unpack the result with 
  354.  
  355.      pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar
  356.  
  357. The BUILD and INSTALL steps are identical to those for Unix.  Some
  358. modules generate Makefiles that work better with GNU make, which is
  359. available from http://www.mks.com/s390/gnu/index.htm.
  360.  
  361. =back
  362.  
  363. =head1 HEY
  364.  
  365. If you have any suggested changes for this page, let me know.  Please
  366. don't send me mail asking for help on how to install your modules.
  367. There are too many modules, and too few Orwants, for me to be able to
  368. answer or even acknowledge all your questions.  Contact the module
  369. author instead, or post to comp.lang.perl.modules, or ask someone
  370. familiar with Perl on your operating system.
  371.  
  372. =head1 AUTHOR
  373.  
  374. Jon Orwant 
  375.  
  376. orwant@tpj.com
  377.  
  378. The Perl Journal, http://tpj.com
  379.  
  380. with invaluable help from Brandon Allbery, Charles Bailey, Graham
  381. Barr, Dominic Dunlop, Jarkko Hietaniemi, Ben Holzman, Tom Horsley,
  382. Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan
  383. Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan
  384. Sugalski, Larry Virden, and Ilya Zakharevich.
  385.  
  386. July 22, 1998
  387.  
  388. =head1 COPYRIGHT
  389.  
  390. Copyright (C) 1998 Jon Orwant.  All Rights Reserved.
  391.  
  392. Permission is granted to make and distribute verbatim copies of this
  393. documentation provided the copyright notice and this permission notice are
  394. preserved on all copies.
  395.  
  396. Permission is granted to copy and distribute modified versions of this
  397. documentation under the conditions for verbatim copying, provided also
  398. that they are marked clearly as modified versions, that the authors'
  399. names and title are unchanged (though subtitles and additional
  400. authors' names may be added), and that the entire resulting derived
  401. work is distributed under the terms of a permission notice identical
  402. to this one.
  403.  
  404. Permission is granted to copy and distribute translations of this
  405. documentation into another language, under the above conditions for
  406. modified versions.
  407.  
  408.